package com.example.base_model.room.dao

import androidx.room.Dao
import androidx.room.Delete
import androidx.room.Insert
import androidx.room.OnConflictStrategy
import androidx.room.Query
import androidx.room.Transaction
import androidx.room.Update
import com.example.base_model.room.bean.User
import com.example.base_model.room.bean.UserWithPets
import kotlinx.coroutines.flow.Flow

/**
 * @Author jiangKunKun
 * @CreateDate 2025/7/29
 * @Description Room DAO (Data Access Object) 接口，用于定义对 [User] 实体及其关联数据的数据库操作。
 * @SpittingGrooves
 */
@Dao // 标记这是一个 Room 数据访问对象接口
interface UserDao {

    /**
     * 插入单个用户。如果发生主键冲突，则替换现有用户。
     * @param user 要插入的用户对象。
     */
    @Insert(onConflict = OnConflictStrategy.REPLACE) // 插入用户，如果冲突则替换
    suspend fun insertUser(user: User)

    /**
     * 插入多个用户。如果发生主键冲突，则替换现有用户。
     * @param users 要插入的用户对象列表。
     */
    @Insert(onConflict = OnConflictStrategy.REPLACE)
    suspend fun insertUsers(users: List<User>)

    /**
     * 更新现有用户。
     * @param user 要更新的用户对象。
     * @return 数据库中受影响的行数。
     */
    @Update
    suspend fun updateUser(user: User): Int // 返回受影响的行数

    /**
     * 删除单个用户。
     * @param user 要删除的用户对象。
     * @return 数据库中受影响的行数。
     */
    @Delete
    suspend fun deleteUser(user: User): Int // 返回受影响的行数

    /**
     * 根据用户 ID 删除用户。
     * @param userId 要删除用户的 ID。
     * @return 数据库中受影响的行数。
     */
    @Query("DELETE FROM users WHERE id = :userId")
    suspend fun deleteUserById(userId: Int): Int

    /**
     * 删除多个用户。
     * @param users 要删除的用户对象列表。
     * @return 数据库中受影响的总行数。
     */
    @Delete
    suspend fun deleteUsers(users: List<User>): Int // 返回受影响的总行数

    /**
     * 删除所有用户。
     * @return 数据库中受影响的行数 (即删除的用户数量)。
     */
    @Query("DELETE FROM users") // 删除所有用户
    suspend fun deleteAllUsers(): Int // 返回删除了多少行

    /**
     * 根据用户 ID 查询用户。
     * @param userId 要查询用户的 ID。
     * @return 匹配的用户对象，如果不存在则返回 null。
     */
    @Query("SELECT * FROM users WHERE id = :userId") // 根据 ID 查询用户
    suspend fun getUserById(userId: Int): User? // 返回匹配的用户或 null

    /**
     * 查询所有用户，并按用户名称升序排序。
     * @return 所有用户对象的列表。
     */
    @Query("SELECT * FROM users ORDER BY name ASC") // 查询所有用户，并按名称升序排序
    suspend fun getAllUsers(): List<User>

    /**
     * 查询所有用户，并按用户名称升序排序，以 Flow 形式返回，实现响应式数据流。
     * 当数据库中的数据发生变化时，Flow 会自动发出新数据。
     * @return 包含所有用户对象的 Flow。
     */
    @Query("SELECT * FROM users ORDER BY name ASC") // 查询所有用户，并按名称升序排序
    fun getAllUsersFlow(): Flow<List<User>>

    /**
     * 查询所有用户及其关联的宠物。此操作是事务性的，以确保数据一致性。
     * 需要使用 `@Transaction` 注解，因为 Room 会先查询 User，再查询 Pet，需要事务保证两者一致性。
     * @return 包含用户及其宠物信息的 [UserWithPets] 对象列表。
     */
    @Transaction // 必须加 @Transaction：因为 Room 会先查 User，再查 Pet，需要事务保证一致性
    @Query("SELECT * FROM users")
    suspend fun getAllUsersWithPets(): List<UserWithPets>
}